home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / Guidelines < prev    next >
Encoding:
Text File  |  1988-12-06  |  9.1 KB  |  221 lines
  1. > Wimp.Guidelines
  2.  
  3.  
  4. Compatibility
  5. -------------
  6.  
  7.      *  reserved fields must be set to 0
  8.         ie. reserved words must be 0, and all reserved bits unset.
  9.  
  10.      *  all Wimp calls corrupt R0, whether or not R0 is to contain a result
  11.         other registers are preserved unless used to return results
  12.         flags are preserved unless V is set on exit
  13.  
  14.      *  unknown Wimp_Poll reason codes, messages etc. MUST BE IGNORED
  15.  
  16.      *  applications should check Wimp version number, and either adapt
  17.         themselves if the Wimp is too old, or report an error to the current
  18.         error handler (use OS_GenerateError)
  19.  
  20.      *  beware of giving errors if window handles are unrecognised
  21.              - they may belong to another task
  22.              - it is sometimes legal for their window handles
  23.                to be returned to you (eg. Wimp_GetPointerInfo)
  24.  
  25.      *  Wimp tasks which are modules must obey certain rules (see
  26.         Wimp.Desktop for details)
  27.  
  28.      *  New Wimp tasks that can receive Key_Pressed events MUST pass on all
  29.         unrecognised keys to Wimp_ProcessKey (see Wimp.Text).  Failure to do
  30.         so will result in the 'hot key' facilities not working.
  31.  
  32.  
  33. New Wimp checking
  34. -----------------
  35.  
  36.      *  SWI calls in wrong context:
  37.             new Wimp disallows certain SWIs outside the context of
  38.             Wimp_Initialise ... Wimp_CloseDown
  39.  
  40.      *  "Bad pointer passed to Wimp in R1"
  41.         - this error is returned if R1 < &8000 when passed to one of a range
  42.           of Wimp SWIs which expect R1 to point to a data block
  43.  
  44.      *  The following SWIs can only operate on windows owned by the calling
  45.         task, and will report the error 'Access to window denied' if an
  46.         attempt is made to access another task's window:
  47.  
  48.                 Wimp_CreateIcon     ; (except in icon bar)
  49.                 Wimp_DeleteWindow
  50.                 Wimp_DeleteIcon     ; (except in icon bar)
  51.                 Wimp_OpenWindow     ; send OpenWindowRequest instead
  52.                 Wimp_CloseWindow    ; send CloseWindowRequest instead
  53.                 Wimp_RedrawWindow
  54.                 Wimp_UpdateWindow
  55.                 Wimp_GetRectangle
  56.                 Wimp_SetExtent
  57.                 Wimp_BlockCopy
  58.  
  59.         Note that this also means that a task cannot access its own windows
  60.         unless it is a 'foreground' process, ie. it has not gained control by
  61.         means of an interrupt routine, or is inside its module Die entry, and
  62.         is only active when the Wimp returns to it from Wimp_Poll.
  63.  
  64.  
  65. Wimp_Initialise / Wimp_CloseDown
  66. --------------------------------
  67.  
  68. In order to maintain compatibility with the old single-tasking window system,
  69. new Wimp programs wishing to make use of the multi-tasking features of the
  70. window system must identify themselves to the window manager as follows:
  71.  
  72.         SWI Wimp_Initialise
  73.         Entry:  R0 = latest known version of Wimp (200 = version 2.00)
  74.                 R1 = "TASK"
  75.                 R2 --> description of program (eg. 'Form Editor')
  76.         Exit:   R0 = actual version number of Wimp (*100)
  77.                 R1 = task handle allocated to task
  78.  
  79. Note that R1 does not point at a string containing the word "TASK" - rather
  80. the four bytes of the register are the letters T,A,S,K (low-byte first).
  81.  
  82. When closing down, the application should pass in its task handle, in case
  83. the task is being closed down from within another task (eg. if the task is a
  84. module, it should call Wimp_CloseDown in its Die routine).  It should do this
  85. as follows:
  86.  
  87.         SWI Wimp_CloseDown
  88.         Entry:  R0 = task handle (R1 on exit from Wimp_Initialise)
  89.                 R1 = "TASK"
  90.  
  91. Setting R1 to "TASK" tells the Wimp that the task knows about the new
  92. features of the window system, and that it is prepared to be well-behaved, as
  93. described below.  The version number passed in R0 to Wimp_Initialise is not
  94. currently used, but it will allow for future versions of the Wimp to get
  95. round any incompatibility issues that might occur.
  96.  
  97. The following is a summary of what the Wimp actually does when initialising a
  98. task:
  99.  
  100. Wimp 1.20 and earlier:
  101.  
  102.   Wimp_Initialise
  103.         Set up soft characters (&80..&8F)
  104.         Set up *FX 4,2; *FX 219,&8A; *FX 221..228,2
  105.         *Pointer
  106.  
  107.   Wimp_CloseDown
  108.         Reset *FX 4,2; *FX 219,&8A; *FX 221..228,2
  109.  
  110.  
  111. Wimp 2.00 and later:
  112.  
  113.   Wimp_Initialise:
  114.         If first task:
  115.           Set up soft characters (&80..&85,&8B..&8E)
  116.           Set up *FX 4,2; *FX 219,&8A; *FX 221..228,2; *FX 229,1
  117.           If R1 = "TASK" on entry: SWI Wimp_SetMode to most recent wimp mode
  118.                                    (defaults to configured WimpMode)
  119.           *Pointer
  120.           If R1 = "TASK" on entry: return R1 = task handle on exit
  121.  
  122.   Wimp_CloseDown
  123.         If last task:
  124.           Reset *FX 4,2; *FX 219,&8A; *FX 221..228,2; *FX 229,1
  125.           MODE <configured mode>
  126.           restore screen memory to configured amount
  127.  
  128.   OS_Exit (or Wimp_Poll after Wimp_CloseDown)
  129.         If R1<>"TASK" when Wimp_Init called,
  130.           and not last task:
  131.             MODE <configured mode>
  132.             restore screen memory to configured amount
  133.             Set up soft characters (&80..&85,&8B..&8E)
  134.             Set up *FX 4,2; *FX 219,&8A; *FX 221..228,2; *FX 229,1
  135.  
  136. #### this last bit is not strictly true !!! ####
  137.  
  138.     The last set of calls ensure that an old-style (or non-Wimp) task
  139.     exitting does not mess up the state of the machine for the remaining
  140.     tasks.  In contrast, when a multi-tasking application quits, it is relied
  141.     on by the Wimp not to have changed mode etc.
  142.  
  143. ################################################
  144.  
  145.  
  146. Compatibility:
  147.  
  148. Wimp ensures that the new Wimp_Poll reason codes are not returned to old tasks
  149. Any windows currently open are made invisible
  150.   - a large window with bg colour 15 is opened to cover up the other windows
  151.   - it has the 'backwindow' bit (bit 11) set, so windows can't get under it
  152. Menu clicks on the background are returned to the task
  153.   - the window handle is returned as -1
  154.   - when multi-tasking, menu clicks on the background are ignored
  155. None of the other tasks is called while the old-style task is running
  156.  
  157. When a new task is started, the Wimp enables escape condition generation
  158. using *FX 229,0.  If/when the task subsequently calls Wimp_Initialise with R1
  159. = "TASK" (ie. it becomes a new-style task), escape condition generation will
  160. be disabled using *FX 229,1 (the escape key returns ascii code &1B instead). 
  161. Thus old-style tasks will run with escape initially enabled by the Wimp
  162. (although they can change it themselves if they want), and so compatibility
  163. is maintained.
  164.  
  165. Note that multi-tasking programs must not call Wimp_Poll while they have
  166. escape condition generation enabled.  If the task calls *FX 229,0 to enable
  167. escape conditions, it must call *FX 229,1 and *FX 124 (in that order) before
  168. calling Wimp_Poll again (*FX 124 acknowledges any pending escape condition).
  169.  
  170. When the task exits, and there are other tasks to run, the screen is reset to
  171. its original mode and any running tasks are restored.
  172.  
  173.  
  174. Guidelines for new-style (multi-tasking) Wimp programs
  175. ------------------------------------------------------
  176.  
  177. Do not set mode/palette unless absolutely necessary
  178.   - if you do, then use Wimp_SetMode and Wimp_SetPalette
  179. Try to survive in any mode (using icons should make this easy)
  180.  
  181. If possible, rely on the user having at least one 'application window' open
  182. for your task to get input through.  When all application windows have been
  183. closed, the task should exit (& unload itself).
  184.  
  185. 'Resident' programs, such as utilities, should get themselves an icon on the
  186. icon bar, using Wimp_CreateIcon with window handle -1.  They should respond
  187. to MENU_click on the icon by bringing up a small menu with the following
  188. options available:
  189.  
  190.         About <util-name> =>            ; information window
  191.         Quit                            ; kills the program
  192.  
  193. Any other options should go between these two.  SELECT on the icon should
  194. cause an application window to be opened (or whatever is appropriate).
  195.  
  196. Do not open any immoveable windows!  These can obscure other tasks'
  197. immoveable windows, or even the icon bar, and so are very undesirable.  In
  198. general, pane windows or moveable 'option' windows are better.
  199.  
  200. Escape handling in the new system is handled by detecting the ascii 27 code
  201. being returned from read-character; escape condition generation has been
  202. disabled by using *FX 229,1.  Thus an application can normally only detect
  203. escape if it owns the caret.  If an applications wishes to perform some long
  204. operation without calling Wimp_Poll, then it can re-enable escape condition
  205. generation in order to be able to abort the operation, but it must be careful
  206. to restore escape condition state before calling Wimp_Poll again (it should
  207. also cancel any current escape condition, just to be on the safe side):
  208.  
  209.         SYS "OS_Byte",229,0,0 TO ,oldstate%     ; re-enable esc conditions
  210.         ...
  211.         <perform long-winded operation>
  212.         ...
  213.         SYS "OS_Byte",229,oldstate%,0           ; restore old state
  214.         SYS "OS_Byte",124                       ; clear escape condition
  215.         <return to Wimp_Poll>
  216.  
  217. Note that it is VERY IMPORTANT that the escape condition generation is
  218. disabled before calling Wimp_Poll, since the other Wimp tasks will not be
  219. expecting escape conditions to arise.
  220.  
  221.